Copyright: Made with EasyHelp/Web (www.easyhelp.com)


Welcome to FormPal Fast-track CGI Form Creator

Version Information

Support

Introduction to FormPal

Installation

Setting Up Web Server

FormPal User Interface

Web Tab

Database Tab

Form Tab

File Menu

Build Menu

Building a Web Form

About the World Wide Web and CGI

Basic Components of a Working Web Form

Design Check List

Working with the Web tab

Working with the Database tab

SQL Data Types

Working with the Form tab

HTML Form Controls

Working with the Input Control Dialog

Creating a Radio Button Group

Creating a Checkbox Group

Working with the Text Area dialog

Working with the List Box dialog

Validating Form Fields

Working with the Define Actions Dialog

Defining actions for submit buttons

Customizing Script Templates

Insert Record

Delete Records

Update Records

Select Records

Working with SQL Criteria Grid

Send Email

Working with the Attachment Dialog

Respond to Browser

Working with the Query Report Dialog

Selecting multiple cells in the Query Report dialog

Post HTML Form

Set HTTP Cookies

Read or Write File

Perl Code Block

Conditional Statement

FormPal Variables

Building CGI Scripts

Publishing a Web Form

Testing a Web Form


Version Information

This version is 6.00.000, Sep. 23, 2002.

Runs under Window 95/98/NT/2000/ME/XP.


Support

support@munica.com

1-514-481-5096

http://www.munica.com

Munica Corporation

2140 Grey Ave.  Suite 2

Montreal, QC H4A 3N4

Canada


Introduction to FormPal

FormPal is an intuitive tool for designing customized Web fill-out forms. FormPal lets you create forms to access relational databases, generate dynamic contents and send emails. FormPal provides everything you need to create feature-rich data-driven Web sites.

FormPal has an integrated HTML form editor, database administration tool, query builder, FTP script installer and easy-to-use script templates for validating data, sending email, accessing relational databases, generating query reports and creating multiple-step forms.

FormPal's HTML form editor lets you quickly create HTML forms in a visual environment. You can also edit HTML forms created by other HTML editors such as Dreamweaver, GoLive or FrontPage.

FormPal's database administration tool lets you quickly create and edit database tables hosted on your Web site.

FormPal's query builder lets you quickly create SQL query forms. It includes an easy-to-use query report designer to help you format data retrieved from one or more databases.

The FTP script installer uploads Web forms and CGI scripts to your Web site and sets appropriate file permissions automatically.

FormPal's field validation methods let you validate phone numbers, email addresses, credit card and number fields in your form. You may program multiple submission buttons (including image buttons) in one form.

FormPal is the only product that lets you create completely compatible CGI scripts for both UNIX- and Windows- based Web servers. If you are a Windows NT Web user, FormPal eliminates the problem of setting up a server-side sendmail program on Windows NT by providing a cross-platform sendmail CGI script.


Installation

Installing FormPal from Self-Extracting EXE Archive

1	Run fp60e.exe self-extracting EXE file.

2	Follow the on-screen instructions.

Installing FormPal from ZIP Archive

1	Copy downloaded fp60e.zip to an empty directory.

2	Unzip fp60e.zip.

3	Run SETUP.EXE from the extracted files.

4	Follow the on-screen instructions.


Setting Up Web Server

Configure Perl for Microsoft Personal Web Server

You can build and test CGI scripts on a local Web server such as Microsoft Personal Web Server . Before you use FormPal to test CGI scripts on MS PWS, you need to configure the server so that it can run Perl scripts. The following is a detailed set up procedure.

1	Download latest Perl (5.0 or higher) at http://www.activestate.com

2	Unzip and install Perl on your server .

3	Open Windows REG file c:\windows\regedit.exe.

4	Double-click the entry HKEY_LOCAL_MACHINE.

5	Double-click System.

6	Double-click CurrentControlSet.

7	Double-click Services.

8	Double-click W3Svc.

9	Double-click Parameters.

10	Double-click Script Map.

11	If there is no '.cgi' entry under the Script Map folder, you need to add one. To add a script map, select the Script Map folder and click the right mouse button. Select New and then String Value to add a '.cgi' entry to the Script Map folder.

12	Double-Click the '.cgi' entry in the Script Map folder. An Edit String dialog appears.

13	If you have installed Perl under c:\Perl, then enter

14	c:\Perl\bin\Perl.exe %s %s in the Value Data box.

15	Double-Click the Personal Web Server icon. The Personal Web Manager appears.

16	Double-Click Advanced.

17	Double-Click virtual directory /cgi-bin. An Edit Directory dialog appears.

18	Enter C:\Inetpub\wwwroot\cgi-bin in the Directory box and make sure the checkbox Execute is on.

19	Click OK.

20	Reboot Windows .

If you are reinstalling PWS, you must first delete the InetPub directory created by any previous installation. PWS does not set up proPerly if an old InetPub is around. Once you have reinstalled PWS, you need to re-configure your PWS for Perl scripts by following the above procedure.

Configure Perl for Microsoft IIS 2.0 - 3.0

If you are running your own Windows NT server with Microsoft IIS 2.0 or 3.0, you need to configure IIS so that it runs Perl scripts. The following is a detailed set up procedure for Windows NT.

1	Download Perl 5.0 build 316 or higher at http://www.activestate.com

2	Unzip and install Perl 5.0 on your server .

3	Open NT REG file c:\winnt\regedit.exe.

4	Double-click the entry HKEY_LOCAL_MACHINE.

5	Double-click System.

6	Double-click CurrentControlSet.

7	Double-click Services.

8	Double-click W3Svc.

9	Double-click Parameters.

10	Double-click Script Map.

11	If there is no '.cgi' entry under the Script Map folder, you need to add one. To add a script map, select the Script Map folder and click the right mouse button. Select New and then String Value in the pop-up menu to add a '.cgi' entry to the Script Map folder.

12	Double-Click the '.cgi' entry in the Script Map folder. An Edit String dialog appears.

13	Provided you have installed Perl under c:\Perl, enter

14	c:\Perl\bin\Perl.exe %s %s in the Value Data box.

15	Reboot Windows NT server .

Configure Perl for IIS 4.0

1	Launch the "Microsoft Management Console" in your Start/Programs menu.

2	Open up the "Internet Information Server" node in the tree view.

3	Find your machine name listed and open it. Under it, you should find "Default Web Site"

4	Select "Default Web Site", then, click the right-mouse button. A pop-up menu appears.

5	Select "Properties" on the pop-up menu.

6	In the "Default Web Site Properties" dialog, click the "Home Directory" tab.

7	In the bottom part of this tab, make sure either "Script" or "Execute" is chosen for Permission (either will work fine).

8	Click the "Configuration" button

9	In the "Application Configuration" dialog, click the "Add" button

10	For Executable, type: c:\Perl\bin\Perl.exe %s %s or whatever your Perl path happens to be.

11	For Extension, type .pl or .cgi.

12	Make sure "Script Engine" is checked & click OK.

13	Click OK twice more & you're back to the Management Console.

You may need to be hooked up to a network for TCP/IP services to work. If you're not hooked up to a network (dial-up doesn't count, except for while you're dialed in), you can set up a "fake" network. Just go to "Network Properties" dialog and add the "MS Loopback Adapter". Then under the "Protocols" tab, double-click the "TCP/IP" protocol & make the following settings:

Adapter: MS Loopback Adapter
IP Address: 10.0.0.2
Subnet Mask: 255.255.255.0
Default Gateway: 10.0.0.2


FormPal User Interface

FormPal's main user interface consists of the Web tab, Database tab, Form tab, File menu and Build menu.


Web Tab

The Web tab is where you enter your Web site information. The Web tab must be filled out completely and correctly for FormPal to work correctly. See 'Working with the Web tab' for more information.


Database Tab

The Database tab is where you enter your database server information of your Web site and design database tables for your FormPal projects. The following figure shows a mysql database xyz with a table 'Customer' located on a server called venus.myisp.net. See "Working with the Database tab" for more information.


Form Tab

The Form tab is where you design Web forms and CGI scripts. See "Working with the Form tab" for more information.


File Menu

The File menu is where you create a new FormPal project or save an existing project.


Build Menu

The Build menu is where you build, publish and run your CGI scripts. Use the Build command to generate a CGI script for your form on your local computer. Use the Publish command to ftp your Web form and script to your Web site. Use the Run command to open your form in a Web browser and test your script.


Building a Web Form


About the World Wide Web and CGI

CGI , or Common Gateway Interface , is a standard programming interface between Web server s and external programs. It lets Web sites provide customized programs to process Web form data submitted by a browser client.

When someone submits a Web form, the browser client sends the data to the CGI script of the form. The CGI script processes the data and sends a response back to the browser client.

You can write CGI scripts in many programming languages. The CGI scripts generated by FormPal are Perl language scripts and therefore require Perl to run. If you rent Web space from an ISP, you can be almost certain your Web server supports Perl. If you run your own server however, you need to install Perl on your server and configure your Web server so that it accepts Perl scripts as CGI scripts.

For security reasons, CGI scripts always reside in a designated CGIBIN folder on your Web site. Depending on the set up of your Web server, your CGIBIN folder can be a subdirectory under your main HTML document folder or a directory parallel to your main HTML document folder. Your Web host is the best source to obtain this information.


Basic Components of a Working Web Form

The basic components of a working Web form are:

1	A form to accept visitors' inputs.

2	A CGI script to process visitors' inputs.

3	A CGI BIN directory on the Web site to store CGI scripts.

4	Perl version 5 or higher on the Web server .


Design Check List

The following are the steps to build a Web form and its CGI script.

1	Click New on the File menu to create a new project .

2	Enter Web site information in the Web tab of the project. See 'Working with the Web tab' for more information.

3	If you plan to access databases with your form, create and edit data sources and tables in the Database tab. See 'Working with the Database tab' for more information.

4	Create and edit your form in the Form tab . See 'Working with the Form tab' for more information.

5	Add actions for each form submission button by clicking  [image]  in the Form tab . See 'Designing CGI scripts '.

6	Build the script. See 'Building CGI Scripts'.

7	Publish the form and script. See 'Publishing Web Form'.

8	Test the form. See 'Testing Web Form'.


Working with the Web tab

The following fields in the Web tab must be filled out in order for FormPal to generate CGI scripts for your Web site.

Server Type	Choose the type of operating system of your Web server. There are two choices: Windows 95/98/NT/2K/XP or Others.
Perl 5 Path	Perl is the program on your server that executes your CGI scripts. You need to specify its path only if you use a UNIX server. The usual location of Perl on Unix is '/usr/bin/perl' or  '/usr/local/bin/perl'. Your Web host is the best source for this information. If you administer your own server, you need to download a copy of Perl and install it on your server. Perl comes with most Unix and Linux distributions.  www.activestate.com provides a Win32 port for Perl for NT/2000 Web users.
Name Servers	Name servers of your Web domain are needed when you want to build a form that validates whether an email address is a deliverable one. You can find out the name servers for your domain from your domain name registrar. For instance, if you have a dot com name such as xyz.com, you can go to http://www.netsol.com/cgi-bin/whois/whois to find out your domain servers. Name servers usually look like "NS.mywebhost.com" or "NS1.mywebhost.com".
CGI Script Extension	Default file extension for CGI scripts. For security reasons, many Web hosts put restrictions on the type of scripts allowed to run on their server. The script extension is usually '.cgi' or '.pl' .
File Upload Method	This is the method that you use to upload Web pages and scripts to your Web site. It is usually via FTP. However, if you develop scripts on the Web server you administer yourself, you may copy your forms and scripts directly to your HTML and CGIBIN folder.
FTP Hostname	If your upload method is FTP, enter your FTP hostname in this field. Your FTP server frequently runs on the same computer as your Web server. For example, if your Web site URL is http://www.yourdomain.com, your FTP server could be www.yourdomain.com or ftp.yourdomain.com. Ask your Web host for this information. If you upload files using direct copy , ignore the FTP Hostname, the FTP User Name and the FTP Password fields.
FTP User Name	Log in user name for the FTP server .
FTP Password	Log in password for the FTP server .
FTP Passive Mode	Enable FTP Passive Mode if you want to upload data from behind a firewall.
Home Page URL	This is the URL of your home page. If you have your own domain name, it should be 'http://www.yourdomain.com'. If you don't have have your own domain name, it should look something like 'http://www.yourisp.com/~username'.
Home Page FTP Path	This is the file path of your home page on the FTP server. It must point to the same page as your Home Page URL. Since many FTP servers use a virtual path, the path entered here may not be the same as the physical file path on the server. For instance, the FTP file path of your home page could be /web/index.html, but the file could physically reside at c:/inetpub/www/xyzcompany/web/index.html. The best way to locate your home page's FTP file path is by clicking the browse button next to this field.
CGI BIN URL:	This is the URL of your CGI BIN. CGIBIN is a designated folder for your CGI scripts . If you have your own domain name, it is usually 'http://www.mydomain.com/cgi' or 'http://www.mydomian.com/cgi-bin'. If you do not have your own domain name, it may look like 'http://www.yourisp.com/~username/cgi'.
CGIBIN FTP Path	This is the path of your CGIBIN folder on the FTP server. It is usually a directory called 'cgi' or 'cgi-bin' that is parallel or under your HTML document folder. For example, Mike's HTML document directory is '/home/mike/html'. His CGIBIN path could be '/home/mike/html/cgi' or '/home/mike/cgi'. Ask your Web host for this information.
Sendmail Path	This is the path of sendmail program on your server. It is usually "/usr/lib/sendmail". Ask your Web host for this information.
SMTP Hostname	If you do not have access to sendmail, you may also send email with an SMTP mail server. Your mail server usually looks like "mail.yourdomain.com" or "smtp.yourdomain.com". Ask your Web host for this information.
SMTP Authentication	Some Web host requires SMTP authentication before allowing a script to access their SMTP server. If your Web host requires SMTP authentication, you need to provide your POP hostname, user name and password in order to send email.


Working with the Database tab

If you want to access a database with your Web form, you must first define your data source in the Database tab. A data source points to the location of a database just like a file path points to a file. A data source is described by database name, driver type, host computer for the database server, account name and password. Once you've described your data source, you can design tables and create them on your Web site.

A table is a placeholder for records. For instance, you can have a phonebook table that holds people's contact information.  Each record in your phonebook may contain name, phone number and email address a person. Name, phone number and email address are called fields. Fields store pieces of information related to a record.

The Database tab provides the following features to help you work with databases on your Web site.

•	Click [image] to add a data source. A data source specifies the location of a database. Data source name must contain only alphanumeric and underscore characters beginning with a letter. "PhoneBook" and "Sales_2002" are valid names, "Phone Book" and "2002Sales" are not.  You may work with multiple data sources in a project.

•	Click [image] to add a table belonging to the selected data source. Before you add a table, you must first select a data source and then click [image]. If you do not have a data source, you must add one first.

•	Click [image] to delete the selected data source or table.

•	Double click on a data source or table, to modify its name.

•	Click [image] to create the tables on the database server. Any modification in the Database tab is not updated on your remote database server until you click [image]. When you click [image], a dialog will pop up and ask you to upload dbadmin.cgi to your server.  Your answer should be 'Yes' so that dbadmin.cgi will create the tables on the database server. If a table with the same name already exists on the server, another dialog will pop up and ask whether you want to delete the existing table and write the new one. If your answer is 'Yes', the existing table will be deleted, its data lost and the new table will be created on the server. If your answer is 'No', nothing will be done. However, you can rename your table and try again.

When you select a data source in the tree control (left hand window), its attributes are displayed on the right. The data source attributes are described as follows:

Driver	The name of your database driver. We currently support mysql. Look for MS Access, MS SQL, Oracle and other database drivers in upcoming releases.
Host	The host name of your database server. For example, acedb.myhost.com. When you rent database services from your Web host, they will tell you where your database is hosted and give you a user name and password to access your database.
Port	The port number of your database server. If you leave it as 0, the default port number for the database server will be used.
Database	The name of your database.
User name:	Log in user name for your database
Password:	Log in password for your database

When you select a table in the tree control, a list of table fields will be displayed in the table definition grid on the right. The following are the field attributes:

Field Name	The name of a field. For instance, an address book table can contain fields such as 'Name', 'Email', 'Address' and so on. "Email" is the name of the field that holds an email address.
Data Type	The data type of a field. For instance, character string type (CHAR) is used for fields that hold people's name and email address; decimal number type (DECIMAL) is used for fields that hold salary and product price; date type (DATE) is used for fields that hold people's birthdate; See 'SQL Data Types'.
Field Size	Data type length. Field size helps database server to allocate enough space to store data for this field. For instance, if you have a "Name" field of type CHAR, you may want to set Field Size to 30 so that you can store names with up to 30 characters. See 'SQL Data Types' for more information.
Null/Not Null	Null/Not Null is a rule used by the database server to ensure required fields of a record are properly filled out before adding it to the database. If Not Null is set for a field, the field is a required field, i.e., the database server will not add a record to the database if this field is undefined. If Null is set for a field, the field is not a required field, i.e., the database server will add a record to the database even if this field is undefined.
Index	Indicate whether you want to index this field. Searching and sorting are much faster on fields that are indexed.
Default Value	Default value for the field. When adding a new record to a table, default value is used if the field is undefined.


SQL Data Types

The data type of a field specifies what kind of information it will hold (characters, numbers, dates and so on) so that the system will know how the data is stored.

Character data types hold letters, numbers and special characters

CHAR	Holds a fixed-length field with a maximum length of 255 characters. If a record uses less space than is allocated to it, the extra space will be padded with zero. You may use CHAR type to store names, zip codes and phone numbers, i.e., the type of information with uniform or nearly uniform length.
VARCHAR	Holds a variable-length field with a maximum length of 255 characters. You may use VARCHAR type fields to store notes and product descriptions, i.e., the type of information with uneven length.
TINYBLOB or TINYTEXT	Holds a BLOB or TEXT field with a maximum length of 255 characters. TEXT field holds letters, numbers and special characters. BLOB holds codes, images and hexadecimal data.
MEDIUMBLOB or MEDIUMTEXT	Holds a BLOB or TEXT field with a maximum length of 16777215 characters.
LONGBLOB or LONGTEXT	Holds a BLOB or TEXT field with a maximum length of 4294967295 characters.
BLOB or TEXT	Holds a BLOB or TEXT field with a maximum length of 65535 characters.
Whole number types hold integers only (no fractions or decimals)

TINYINT	Holds a very small integer. SIGNED range is -128 to 127. UNSIGNED range is 0 to 255.
SMALLINT	Holds a small integer. SIGNED range is -32768 to 32767. UNSIGNED range is 0 to 65535.
INT or INTEGER	Holds a normal-sized integer. SIGNED range is -2147483648 to 2147483647. UNSIGNED range is 0 to 4294967295.
MEDIUMINT	Holds a medium-sized integer. SIGNED range is -8388608 to 8388607. UNSIGNED range is 0 to 16777215.
BIGINT	Holds a large integer. SIGNED range is -9223372036854775808 to 9223372036854775807. UNSIGNED range is 0 to 18446744073709551615
Decimal data types holds numbers with fractions

Real or Double	Holds a double-precision floating-point number that cannot be unsigned. Allowable values are -1.7976931348623157E+308 to -2.2250738585072014E-308, 0, and 2.2250738585072014E-308 to 1.7976931348623157E+308. You may define the display width (number of digits before the decimal point) and the decimal precision (number of digits after the decimal point).
Float	Holds a floating-point number that cannot be unsigned. Allowable values are -3.402823466E+38 to -1.175494351E-38, 0, and 1.175494351E-38 to 3.402823466E+38. You may define the display width (number of digits before the decimal point) and the decimal precision (number of digits after the decimal point).
Numeric or Decimal	Holds an unpacked floating-point number that cannot be unsigned. Behaves like a CHAR column: ``unpacked'' means the number is stored as a string, using one character for each digit of the value. Both the display width (number of digits before the decimal point) and the decimal precision (number of digits after the decimal point) must be specified.
Date data types hold date and time

DATE	Holds date in the YYYY-MM-DD format
TIME	Holds time in the HH:MM:SS format
DATETIME	Holds date and time in the YYYY-MM-DD HH:MM:SS format
TIMESTAMP	Holds date and time in the YYYYMMDDHHMMSS format. Use this in situations where you would like to record the date and time of an entry into the table. This field is automatically set to the current date and time if no value is specified when inserting records, or if the value is specified as NOW(). • If length is 14, TIMESTAMP is YYYYMMDDHHMMSS.  • If length is 12, TIMESTAMP is YYMMDDHHMMSS.  • If length is 8, TIMESTAMP is YYYYMMDD.  • If length is 6, TIMESTAMP is YYMMDD.
Other data types

ENUM	A string type that can accept one value from a list of previously defined possible values. For instance, you can make the "Country" field of your address book an ENUM type. An ENUM type can have up to 65535 elements.
SET	A string type that can accept one value from a list of previously defined possible values. A SET type can have up to 64 elements.


Working with the Form tab

The Form tab contains the following fields:

HTML File:	This is the local file path of your HTML file. Click [image] to create a new HTML file with a form. Click [image] to open an existing HTML file. Click [image] to save current HTML file. Press down [image] and then click [image] to format HTML form automatically.
Form Title:	This is the title of your HTML form Click [image] to edit current HTML form in an external HTML editor. Click [image] to set the default external HTML editor.
Form List:	You may have more than one form in an HTML file. This field indicates the form you want to work with.
List of Fields:	Shows a list of fields found in the current form.  Double click the Name column of a field to edit its name. Double click the Edit column of a field to edit it in a dialog box. Double click the Value column of a field to edit its default value. Double click the Content column of a field to set the validation method. See 'Validating Form Fields'. Click any of the Form Control buttons to add a field. Click [image] to delete the selected fields. Hold the 'Shift' key, click the left mouse button once, move the mouse to a new cell and click left mouse button again to select more than one field. Click [image] to edit the selected field. Same as clicking the Edit column. Click [image] to add actions for your CGI script.


HTML Form Controls

The following are controls you can add to your form.

	Check box
	Radio button
	Text box
	Password box
	Hidden text box
	Buttons
	File upload field
	Multiple-line text box
	Drop-down list box
	List box


Working with the Input Control Dialog

When you click [image], [image], [image], [image], [image], [image], or [image], an Input Control dialog appears where you can edit attributes for these controls. The following is a list of fields in the Input Control dialog.

Name	Name of the form field.
Maximum Length	Maximum number of characters allowed in the form field. If maximum length is greater than the size of a field , the visitor is able to scroll to access text that is not visible.
Size	The number of characters to be displayed in the form field. It determines the horizontal length of the field.
Value	The initial value of the form field.
State	The initial state of a checkbox or radio button. When the value is "CHECKED", the checkbox or radio button will be checked when the browser client displays the form. It is used only when the field is a checkbox or radio button.
Alternative Text	Alternative text for the image button. It is used only when the form field is an image button.
Image URL	The URL of the image file used by an image button. It is used only when the form field is an image button.


Creating a Radio Button Group

A radio button group ensures that only one choice can be made at a time and only the value of the selected choice is sent to the CGI script. You make a radio button group by giving the same field name to each radio button in the group and placing them together.


Creating a Checkbox Group

A checkbox group allows multiple choices to be made at the same time and only the values of the selected choices are sent to the CGI script. You make a checkbox group by giving the same field name to each checkbox in the group and placing them together.


Working with the Text Area dialog

When you click [image], a Text Area dialog appears for you to create a multiple-line text box. The following is a list of fields in Text Area dialog.

Field	Description
Name	Name of the form field.
Maximum Length	Maximum number of characters allowed in the form field. If maximum length is greater than the size of the field , the visitor is able to scroll to access text that is not visible.
Rows	Maximum number of visible rows in the multiple-line text box.
Columns	Maximum number of visible columns in the multiple-line text box.
Default Value	Initial text in the multiple-line text box.


Working with the List Box dialog

When you click [image] or [image], a List Box dialog appears for you to create a drop-down list, or list box, respectively. A drop-down list box lets you select one item from a list of choices. A list box lets you select multiple items from a list of choices. The following is a list of fields in the List Box dialog.

Field	Description
Name	Name of the form field.
Size	The number of characters to be displayed in the form field. It determines the horizontal length of the field.
List of Choices	List of choices for the list box or drop-down box. Each item in the list has an item name, item value and default selection state. If the default selection state of an item is "SELECTED", the item will be selected when the browser client displays the form. Click 'Add' to add an item to the list of choices. Click 'Delete' to delete the selected item. Click 'Default' to set the default selection state for the selected item. Double click a cell in the grid to edit it.


Validating Form Fields

The following are supported field validation methods:

Field Content Type	Description
ANYTHING	No field validation is applied.
NOT NULL	The field must not be empty.
CREDIT_CARD	Requires a valid credit card number in the field. It accepts the following credit card numbers: American Express, Diner's Club, Discover, Master Card, Visa and JCB. However, it can't tell whether there is enough credit on the card.
EMAIL	Requires an email address (syntax check only) in the field.
REAL_EMAIL	Requires a deliverable email address in the field. [Available only in Standard and Unlimited Edition]
EXPIRATION_DATE	Requires a valid credit card expiration date .
DECIMAL	Requires a decimal number in the field.
INTEGER	Requires an integer in the field.
PHONE	Requires a telephone number in the field.
image/*	Requires an image file in a file upload field. [Available only in Unlimited Edition]
text/*	Requires a text file in a file upload field. [Available only in Unlimited Edition]
audio/*	Requires an audio file in a file upload field. [Available only in Unlimited Edition]
video/*	Requires a video file in a file upload field. [Available only in Unlimited Edition]
application/octet-stream	Requires a binary file in a file upload field. [Available only in Unlimited Edition]
Designing CGI Scripts

When you click [image] in the Form tab, or the Build command in the Build menu, a Define Actions dialog appears where you can define a list of actions for each submit or image button in your form.


Working with the Define Actions Dialog

The Define Action dialog has the following fields:

Field	Description
Button Name	A list of submit buttons.
Action List	A list of actions to be executed for each submit button. Each action must have a unique name. Action names must be alphanumeric (including underscore '_') strings beginning with a letter and without space. For example, "Send_Mail_Action' and 'Query1' are valid action names. '1Query' and 'Send Mail Action' are not.


Defining actions for submit buttons

1	Select the button you wish to program in the Button Name list box.

2	Move the mouse on the New button, and select a script template from the pop up menu.

3	Customize the selected script template. See 'Customizing Script Template'.

4	Repeat step 2 until finished adding actions for the selected button.

5	Repeat step 1 until every button is programmed.

6	Click OK to exit Define Actions dialog.

Double click the action to rename an action.

Select an action and click Delete to delete it.

Select an action and click Edit to modify it.


Customizing Script Templates

FormPal provides a list of script templates to help you quickly create CGI scripts. No programming skill is required since the script templates are designed as easy-to-use dialog boxes. The following is a list of script templates FormPal supports.

Script Template	Description
Insert Record	Insert a new record to a database using an SQL query
Delete Records	Delete existing records from a database using an SQL query
Update Records	Update existing records in a database using an SQL query
Select Records	Select records from a database using an SQL query
Send EmailK NAME	Send emails
Respond to Browser	Redirect browser to a URL or display a dynamically generated page in a browser client
Post Html Form	Display a dynamically generated HTML form in a browser client
Set HTTP Cookies	Store cookies in a browser client
Read or Write File	Read or write server-side file
Perl Code Block	Execute your own Perl code
Conditional Statement	Execute actions conditionally


Insert Record

[Available in LE, Standard and Unlimited Editions]

An Insert Record action will execute an SQL statement that inserts a record into a table.

The Insert Record tab has the following fields:

Field	Description
Data Source	The datasource of the table to which you wish to add a record, chosen from the list of data sources defined in the Database tab.
Table Name	Select the name of the table to which the record will be added.
Field List	List of fields and their respective values.
1	Click [image] to add all the fields defined in the table selected in Table Name.

2	Click [image] to bind table fields with HTML form fields automatically. Auto binding only works if the names of form fields and table fields are the same. You can also double click a cell in the grid and enter the field names and values in the in-place edit box.

3	Click OK when done.

Click [image] to clear the selected fields and values.

Click [image] to view the SQL query statement for inserting a record into the selected database table.


Delete Records

[Available in LE, Standard and Unlimited Editions]

A Delete Record action will execute an SQL statement that deletes records from a table.

The Delete Record tab has the following fields:

Field	Description
Data Source	The data source of the table from which you wish to delete, chosen from the list of data sources defined in the Database tab
Tables to delete from	The name of the table from which records will be deleted
Criteria for deletion	Criteria for deletion. For instance, you may want to delete records whose  "Email" field matches the email address entered in the HTML form.
1	Select the data source of the table you wish to delete from.

2	Double click the first cell in the Tables to delete from field and select the table from the in place list box.

3	Enter the criteria for deletion. See 'Working with SQL Criteria Grid'.

4	Click OK when done.

Click [image] to clear the selected table name in the Tables to delete from field.

Click [image] to view the SQL query statement for deleting records.


Update Records

[Available in LE, Standard and Unlimited Editions]

An Update Record action will execute an SQL statement that updates records from a table.

The Update Record tab has the following fields:

Field	Description
Data Source	The data source of the table you wish to update, chosen from the list of data sources defined in the Database tab
Fields to Update	The name and value of the fields to be updated
Criteria for updating	Criteria for updating. For instance, you may want to update records whose "Email" field matches the email address entered in the HTML form.
1	Select the data source of the table you wish to update.

2	In the Fields to Update grid, double click a cell in the Table column to select the table you wish to update.

3	Click [image] to add all the fields of the selected table, or double click a cell in the Field column to select the field you wish to display.

4	Double click the Value column and enter the value for the selected field using the in-place edit box or click [image] to bind table fields with HTML form fields automatically. Auto binding only works if the names of form fields and table fields are the same.

5	Enter the criteria for updating. See 'Working with SQL Criteria Grid'.

6	Click OK when done.

Click [image] to clear the selected table fields and values.

Click [image] to view the SQL query statement for updating records.


Select Records

[Available in LE, Standard and Unlimited Editions]

A Select Record action will execute an SQL statement that selects records from a table. If you expect a large number of records to be retrieved from the database, you can fetch a portion and let FormPal handle the browsing controls in your query report.

The Select Record tab has the following fields:

Field	Description
Data Source	data source of the table from which you wish to select data, chosen from the list of data sources defined in the Database tab
Fields to Display	You can choose to display a subset of fields for each record. For instance, if your phonebook table has name, email, address, city, state, zip and country fields, you can choose to display only the name and email fields.
Criteria for selection	Criteria for selecting record from database. For instance, you can retrieve records whose "Email" field matches the email address entered in the HTML form.
Number of rows to display	If you expect a large number of records to be retrieved, you can split the results into multiple pages and let FormPal generate a browsing script for you. The number in this field determines maximum number of rows to be displayed per page. FormPal can generate a browsing script to handle "Go To First Page", "Go To Previous Page", "Go To Next Page", and "Go To Last Page" actions. All you need to do is to insert browsing controls in your query report. See "Working with the Query Report Dialog".
1	Select the data source of the table you wish to select records from.

2	In the Fields to Display grid, double click a cell in the Table column to select the table you wish to select from.

3	Click [image] to add all the fields of the selected table, or double click a cell in the Field column to select the field you wish to display.

4	Enter the criteria for selection. See 'Working with SQL Criteria Grid'.

5	Click OK when done.

Click [image] to clear selected table fields and values.

Click [image] to view the SQL query statement for selecting records from tables.


Working with SQL Criteria Grid

You can design comprehensive SQL criteria in the SQL Criteria Grid found in the "Delete Records", "Select Records" and "Update Records" tabs. SQL Criteria are used to select records that meet certain conditions from a database.

An SQL criterion consists of one or more simple criteria joined by 'AND' and 'OR' operators. The simplest criterion takes the form: (Table.Field Operator Value). For instance, "(Address.Name = 'Nathan')" says: only he whose name is Nathan qualifies. You can use 'AND' or "OR' operators to join simple criteria to form a more complex query. For instance, "((Address.Name = 'Nathan') AND (Address.Age = 25))" says: only he whose name is Nathan and who is 25 years old qualifies. The required value of a field can be a static string such as 'Nathan' or taken from a Web form such as '@{$FORM{'Name'}}'. You can double click the Value row to enter the required value or select a form variable from the in-place list box.

The following is a list of commonly used SQL comparison operators.

•	The '=' operator tests whether Table.Name is equal to Value.

•	The '>' operator tests whether Table.Name is greater than Value.

•	The '<' operator tests whether Table.Name is less than Value.

•	The '>=' operator tests whether Table.Name is greater than or equal to Value.

•	The '<=' operator tests whether Table.Name is less than or equal to Value.

•	The '<>' operator tests whether Table.Name is not equal to Value.

•	The 'BETWEEN' operator tests whether Table.Name falls into the range defined by Value. For example, (Address.Age BETWEEN (25, 35)) matches any record with age between (and including) 25 and 35 years. (Address.Age BETWEEN (25, 35)) is equivalent to ((Address.Age >= 25) AND (Address.Age <= 35))

•	The 'NOT BETWEEN' operator tests whether Table.Name does not fall into the range defined by Value. For example, (Address.Age NOT BETWEEN (25, 35)) matches anyone who is younger than 25 years old or over 35 years old. (Address.Age NOT BETWEEN (25, 35)) is equivalent of ((Address.Age < 25) OR (Address.Age > 35))

•	The 'LIKE' operator tests whether Table.Name matches the string pattern stored in Value. For example, (Address.Name Like 'Mc%') matches anyone whose name starts with "Mc" such as "McCord" and "McRae". The '%' wildcard matches any string of zero or more characters. You can use '_' in your pattern to match any single character. For example, (Address.Name LIKE 'Mar_') matches names such as 'Mark' and 'Mary'.

•	The 'IN' operator tests whether Table.Name is a member of the set defined by Value. For example, (Address.State IN ('CA', 'MA', 'CO')) matches state such as 'CA', 'MA' or 'CO'.

•	The 'NOT IN' operator tests whether Table.Name is not a member of the set defined by Value. For example, (Address.State NOT IN ('CA', 'MA', 'CO')) matches any state that is not 'CA', 'MA' or 'CO'.

The following figure shows the criteria that select everyone whose name is 'Nathan' and who is 25 years old. The criteria written in SQL are: ((Address.Name = "Nathan") and (Address.Age = 25)).

The following figure shows the criteria that select everyone whose name is 'Nathan' and who is between 25 and 35 years old. The criteria written in SQL are: ((Address.Name = "Nathan") and (Address.Age >= 25) and (Address.Age<=35)).

The following figure shows the criteria that select everyone whose name is 'Nathan' or 'Sally'. The criteria written in SQL are: ((Address.Name = 'Nathan') or (Address.Name = 'Sally'))

The following figure shows the criteria that select everyone whose name is 'Nathan' and who is between 25 and 35 or whose name is 'Sally' and who is between 45 and 55. The criteria written in SQL are: (((Address.Name = 'Nathan') and (Address.Age >= 25) and Address.Age <= 35)) or ((Address.Name = 'Sally') and (Address.Age >= 45) and Address.Age <= 55)))


Send Email

[Available in LE, Standard and Unlimited Editions]

The following is a list of fields in the Send Email tab.

Field	Description
Sender's Name	Email sender's name. You can enter a static name or use data submitted from a Web form. Click the right mouse button to enter a form variable if you wish to use data submitted from a form as email sender's name.
Sender's Email Address	You can enter a static email address or use the email address submitted from a Web form. Click the right mouse button to enter a form variable if you wish to use the email address submitted from a form as the sender's email address.
Recipient's Email Address	You can enter a static email address or use the email address submitted from a Web form. Click the right mouse button to enter a form variable if you wish to use the email address submitted from a form as the recipient's email address. You may enter multiple email addresses here as long as they are separated by a space or comma.
CC	You can enter a static email address or use the email address submitted from a Web form. Click the right mouse button to enter a form variable as the email address you wish to CC to. You may enter multiple email addresses here as long as they are separated by a space or comma.
Subject	You can enter a static subject line or use data submitted from a Web form. Click the right mouse button to enter a form variable if you wish to use data submitted from a form as part of the subject line.
Attachments	You may attach any number of files with an email message. Click [image] to add an attachment. See 'Working with the Attachment Dialog'. Click [image] to edit the selected attachment. See 'Working with the Attachment Dialog'. Click [image] to delete the selected attachment.
Format Message	Enter the email message here. If you enter nothing, a default email message will be used consisting of all the fields from the submitted form.  Click [image] to create a file to hold your email message. It can be a text or html file. While the cursor is in the edit area of the Format Message box, click the right mouse button to insert FormPal variables in your message. This way you will be able to put data submitted by the Web form as part of the email message. Click [image] to use an existing file as your email message file. Click [image] to save current email message file.


Working with the Attachment Dialog

[Available in Standard and Unlimited Editions]

The attachment dialog lets you specify the attachment file for your email.

The Attachment dialog has the following fields:

Fields	Description
Attachment Type	Specifies whether the attachment is a text file or binary file. A text file contains letters, numbers and special characters. Plain text files and HTML files are examples of text files. Binary files contain codes, images, videos and other hexadecimal data. Word documents, GIF images and executable files are examples of binary files.
Source	The data to be used as an attachment. It can be any file stored on your Web site or dynamic data uploaded to your site by a Web form.   Click [image] to create a new file as attachment. The file you select here is a local file. FormPal will upload the file to your Web site automatically. Click [image] to locate an existing file as attachment. Click [image] to save current attachment file. If you wish to attach the file uploaded by a form with the email message, simply click the right mouse button to insert a file upload handle in the Source field. This feature lets you create a form so that visitors can email a file from their local computer to you. For instance, an online video archive may want a submission form that lets people enter the title and description of their video and select the video they want to submit from their local computer. This feature is only available in FormPal Unlimited.


Respond to Browser

[Available in LE, Standard and Unlimited Editions]

A CGI script must send a response to a browser client , otherwise the browser will post "SERVER ERROR" even though the script has finished successfully on the server . You can redirect a browser client to a URL or display a dynamically generated HTML page in the Respond to Browser tab.

Redirect to a URL

1	Click Redirect to a URL.

2	Enter the URL you wish to redirect to. The URL must begin with "http://". For example, "http://www.munica.com". The URL can be static or taken from the submitted Web form. You can create a dynamic URL link by clicking the right mouse button in the URL box to add FormPal variables as part of your URL link.

3	Click OK when done.

Post a Message

1	Click Post a Message.

2	Click [image] to create an HTML template file that will be dynamically generated and displayed in a browser client. While the cursor is in the edit area of the Format Message box, click the right mouse button to insert FormPal variables or a query report in the HTML template file so that data submitted by the Web form or retrieved from databases will be displayed in the dynamically generated Web page. See 'Working with the Query Report Dialog'. Click [image] to use an existing HTML template file. Click [image] to save current HTML template file.

3	Click OK when done.


Working with the Query Report Dialog

[Available in Standard and Unlimited Editions]

The Query Report dialog lets you quickly design a customized query report.

Take the following steps to add data retrieved from a database or submitted from a form to your query report:

1	Select an action or form from the Data combo box.

2	Select a cell in the grid control and then:

•	Click [image] or [image] to insert record indexes horizontally or vertically, respectively. These commands only work when a Select Record action is selected in the Data combo box.

•	Click [image] or [image] to insert field labels horizontally or vertically, respectively. The field labels can be table field labels or form field labels depending on what is selected in the Data combo box.

•	Click [image] to insert horizontally a template for the first row of data retrieved from a database. Highlight the row of data you just inserted, click [image] repeatedly to automatically insert more row templates.

•	Click [image] to insert vertically a template for the first row of data retrieved from a database. Highlight the column of data you just inserted, click [image] repeatedly to automatically insert more columns.

•	Click [image] to add a "Go to First Page" button in the query report.

•	Click [image] to add a "Go to Previous Page" button in the query report.

•	Click [image] to add a "Go to Next Page" button in the query report.

•	Click [image] to add a "Go to Last Page" button in the query report.

•	Apart from data and labels retrieved from your Web form and databases, you can also enter any text you want in the query report. Simply double click a cell and type text in the in-place edit box.

0	Do the following steps to format your query report:

1	Select a range of cells in the grid, and do the following:

•	Click [image] to set cell width.

•	Click [image] to set font style and colour.

•	Click [image] to set cell background colour.

•	Click [image] to clear cell content.

•	Click [image] to merge selected cells into one cell.

•	Click [image] to split merged cells.

•	Click [image] to align text to the left of the cells.

•	Click [image] to align text to the centre of the cells.

•	Click [image] to align text to the right of the cells.

•	Click [image] to align text to the top of the cells.

•	Click [image] to align text to the vertical centre of the cells.

•	Click [image] to align text to the bottom of the cells.

•	Click [image] to set font style to bold.

•	Click [image] to set font style to italic.

•	Click [image] to set font style to underlined.

•	Click [image] to set cell border width, cell padding, cell spacing, and table background colour.

Selecting multiple cells in the Query Report dialog

While holding the SHIFT key, click the left mouse button in the first cell of the range, then place the cursor in the last cell of the range and while holding the SHIFT key, click the left mouse button to complete the selection.


Post HTML Form

[Available in Unlimited Edition]

Post HTML Form lets you create a multiple step Web form. Multiple-step forms are very useful when you need to break a very large form into smaller ones, or when subsequent steps depend on a visitor's inputs from previous steps.

The following sequence shows how a multiple-step form works.

Server:	Post Form1 in a browser client.

Client:  	Submit Form1 and trigger the CGI script of Form1.

Server: 	Server's CGI script does the following:

•	Validate form fields

•	Execute customized actions

•	Cache (store but don't display) data from Form1 in Form2

•	Post Form2 in a browser client.

Client:  	Submit Form2 and trigger the CGI script of Form2.

Server: 	Server's CGI script does the following:

•	Validate form fields

•	Execute customized actions

•	Cache data from Form2 in Form3

•	Post Form3 in a browser client.

…

The above sequence may be repeated as many times as necessary.

A Post HTML Form action lets you validate form fields, cache form fields from the previous step and add customized actions.

The following are the steps to create a multiple-step form:

1	Add form fields for the current step. See 'Working with the Form tab".

2	Click [image] to cache fields from the previous step (including fields cached from an earlier step) as hidden fields. Hidden fields are invisible in a browser client.

3	Click [image] to cache fields from the previous step as is.

4	Click [image] to define actions for the current step. Add a Post HTML Form action in the Define Actions dialog to display the next step. Note, for multiple-step forms, a Post HTML Form action must always be the last action in your action list.


Set HTTP Cookies

[Available in Standard and Unlimited Editions]

When someone visits your site, you can store cookies in that visitor's computer, provided the visitor permits cookies to be written. Cookies are small pieces of information used to track visitor behaviour such as time of last visit. A Web site may store up to 20 cookies in a visitor's computer . Each cookie must be 4 KB or less.

The following are fields in Set HTTP Cookies tab.

Fields	Description
Expiration Date	The expiration date determines how long a visitor's computer can keep the cookie. Your Web site will not be able to retrieve a cookie after it is expired.
Cookie List	List of cookies to save in a visitor's computer. Each cookie has a cookie name, value and security status. If a cookie is secure, it can be retrieved only over a secure HTTP connection, i.e., only Web pages beginning with "https://" will be able to retrieve it. Click Add to add a new cookie. Click Delete to delete an existing cookie. Double click the Name column of a cookie to edit its name. Double click the Value column of a cookie to edit its value. Double click the Secure column of a cookie to enable/disable its security status.
The above example sets two HTTP cookies and makes them expire in 30 days.


Read or Write File

[Available in Standard and Unlimited Editions]

The following are fields in the Read or Write File tab.

Fields	Description
Server-side File Path	Name of the server-side file to be read or written. Click [image] to create a new server-side file. Click [image] to select an existing server-side file. The default folder for this field is $cgibin/data. If you enter a bare filename, i.e., without a path, such 'mylog.log' in this field, you actually point to file $cgibin/data/mylog.log. $cgibin is the FTP path of your CGIBIN. You should use bare filenames as much as possible for this field to make your project more portable.  If you wish to read data from an uploaded file, click the right mouse button to enter a file upload handle in this field. The uploaded data will be stored in the variable $actionname, where actionname is the name of the Read or Write File action. If you wish to upload a file, the file path can be a fixed path such as "/home/xyz/html/myfile.ext" or  "/home/xyz/html/${$FORM{'uploadfield'}}[0]" where 'uploadfield' is the name of the file upload field. ${$FORM{'uploadfield'}}[0] represents the file name of the uploaded file.
File Operation	You can overwrite, append or read the server-side file.
Format Message	Enter the data you wish to write to the server-side file here.  • Click [image] to create a template file to hold the data that will be written to the server-side file. You can put FormPal variables and query reports in the template by clicking the right mouse button while the cursor is in the edit area.  • Click [image] to use an existing template file.  • Click [image] to save current template file. • If you wish to upload a file to a Web site, click the right mouse button in the file path area to insert a file upload handle and leave the edit area blank.


Perl Code Block

[Available in Standard and Unlimited Editions]

If you know Perl , you can add custom Perl code in your CGI scripts.


Conditional Statement

[Available in Standard and Unlimited Editions]

You can use a conditional statement to execute actions when certain conditions are met. For instance, when designing a login form, you may want to display a login error page when wrong user name and/or password are entered.

The following are fields in the Conditional Statement tab.

Fields	Description
Condition Grid	Describe the condition by comparing two values with a comparison operator. The simplest conditional statement takes the form: (Value1 Operator Value2). Double click the Value row to enter the first value and second value. Double click the Operator row to enter a comparison operator. The '==' operator tests whether the two values are equal.  The '>' operator tests whether the first value is greater than the second value. The '<' operator tests whether the first value is less than the second value. The '>=' operator tests whether the first value is greater than or equal to the second value. The '<=' operator tests whether the first value is less than or equal to the second value. The '!=' operator tests whether the first value is not equal to the second value. The 'eq' operator tests whether the first character string is equal to the second character string. The 'ne' operator tests whether the first character string is not equal to the second character string.
Action List	List of actions to execute when the condition described in the Condition Grid is met. Move mouse to the New button and select a script template in the pop up menu to add a new action. Click an existing action, and then click Edit to edit it. Click an existing action, and then click Delete to delete it.

The above example shows a conditional statement: If '$Action1->{nrows}' is zero, execute Action1 to, for example, display a login error page.


FormPal Variables

FormPal variables are used to supply dynamic data for many actions. The following is a list of them:

Variables	Description
$FORM{'WWW_DATE'}	Holds the submission date.
$FORM{'WWW_TIME'}	Holds the submission time.
$FORM{'WWW_YEAR'}	Holds the submission year .
$FORM{'WWW_MON'}	Holds the submission month.
$FORM{'WWW_MDAY'}	Holds the submission day.
$FORM{'WWW_WDAY'}	The 'weekday' part of the submission date .
$FORM{'WWW_HOUR'}	Holds the submission hour.
$FORM{'WWW_MIN'}	Holds the submission minutes.
$FORM{'WWW_SEC'}	Holds the submission seconds.
$FORM{'WWW_MILHOUR'}	Holds the submission hour.
$FORM{'WWW_AMPM'}	Holds the noon indicator of the submission time.
$ENV{'HTTP_REFERER'}	The referral HTML page.
$ENV{'HTTP_USER_AGENT'}	Holds visitor's browser name and version.
$ENV{'REMOTE_ADDR'}	Holds the IP address of visitor's computer.
@{$FORM{'field'}}	Holds the values of a form field where 'field' is the name of the field. If a form contains a checkbox group field "field", "@{$FORM{'field'}}" holds all the values that are checked. Use "$FORM{'field'}[0]" to refer to the first value, "$FORM{'field'}[1]" to the second value and so on.
$action->{nrows}	Holds the number of rows affected by a query. "action" must be a Select Records, Delete Records or Update Records action.
$action->{rows}[0]{'field'}	Holds the field value of the first retrieved row. "action" must be a Select Records action. "field" is the name of a field. This variable is not available in FormPal LE.
$action->{index}[0]	Holds the row number of a retrieved row. "action" must be a Select Records action. This variable is not available in FormPal LE.
$action->{DefaultReport}	Holds the default query report for a Select Records action.  This variable is only available in FormPal LE.
$action	Holds the data read from a file. "action" must be a Read or Write File action. This variable is not available in FormPal LE.
$COOKIEJAR{'cookiename'}	Holds the value of a cookie.


Building CGI Scripts

1	Click the Build command on the Build menu.

2	A Define Actions dialog appears. See 'Working with the Define Actions Dialog'.

3	Click OK to generate a CGI script for your form.

The script stays on your local machine until you publish it.


Publishing Web Form
Publishing a Web Form

1	Click the Publish command on the Build menu.

2	A Publish dialog appears. Files that will be uploaded to the Web server are listed in the dialog.

3	Click Upload Now to start uploading files.

The form will be copied to the server-side HTML folder .

The CGI script will be copied to the server-side CGI BIN folder .

The template files will be copied to server-side CGIBIN/templates folder.


Testing Web Form
Testing a Web Form

Once you have built and published your form, you can test it by clicking the Run command on the Build menu. FormPal will open the form in your default Web browser . Fill out the form and click the submit button to test your CGI script.

If you receive "Server Error' from the browser after submitting the form , the cause may be one of the following:

•	Wrong settings in the Web tab .

•	The script does not have permission to execute.

•	Perl is not installed or configured on your Web server .

•	There is no escape character '\' before '$' and '@' in message template s.

•	Insufficient file permission for your template files.